Introduction

This sections describes the Event Handling system. It will show you how it works and how you can use it to listen for security related events.

Events are a nice way to allow additional logic to be executed in response to certain security events. This can be very useful if you want to:

• Provide additional logging

• Audit your application

• Invoke some business logic or process

PicketBox's event system also allows you to use the Event Manager to fire specific security events for your application. You are not tied to only the event types that are provided, you can write your own events and fire them along your application code, leveraging the notification level for security related events in your application.

Handling Events

The event system design is very simple, basically what you need to know is that event handlers can be any class. The only restriction is that the class must have one or more methods annotated with the @EventObserver annotation.

public class UserAuthenticationEventHandler {

    @EventObserver
    public void onSuccessful(UserAuthenticatedEvent event) {
        // do something
    }

    @EventObserver
    public void onUnSuccessful(UserNotAuthenticatedEvent event) {
        // do something
    }

    @EventObserver
    public void onFailed(UserAuthenticationFailedEvent event) {
        // do something
    }

}

The code above demonstrates how to create a class to handle some specific security events. Note that each method is annotated with the @EventObserver annotation.

Now, you just need to register this handler when building the PicketBox configuration as follows.

ConfigurationBuilder configurationBuilder = new ConfigurationBuilder();

UserAuthenticationEventHandler eventHandler = new UserAuthenticationEventHandler();

configurationBuilder.authentication().eventManager().handler(eventHandler);

// proceed with the configuration, create and start the PicketBoxManager

Firing Events

PicketBoxManager picketBoxManager = // get the manager

// gets the event manager from the PicketBox manager
PicketBoxEventManager eventManager = picketBoxManager.getEventManager();

// fires the event
eventManager.raiseEvent(new MyOwnSecurityEvent());

Supported Events

The following tables enlist all event types and handlers and their description.